<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>wordexp</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_010_800">&nbsp;</a>NAME</h4><blockquote>
wordexp, wordfree - perform word expansions
</blockquote><h4><a name = "tag_000_010_801">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="wordexp.h.html">wordexp.h</a>&gt;

int wordexp(const char *<i>words</i>, wordexp_t *<i>pwordexp</i>, int <i>flags</i>);
void wordfree(wordexp_t *<i>pwordexp</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_010_802">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>wordexp()</i>
function performs word expansions as described in the <b>XCU</b> specification, <a href="../xcu/chap2.html#tag_001_006"><b>Word Expansions</b>&nbsp;</a>,
subject to quoting as in the <b>XCU</b> specification, <b>Section 2.2</b>, <b>Quoting</b>,
and places the list of expanded words into the structure
pointed to by
<i>pwordexp</i>.
<p>
The
<i>words</i>
argument is a pointer to a string containing one or more words to be expanded.
The expansions will be the same as would be
performed by the shell if
<i>words</i>
were the part of a command line representing the arguments to a utility.
Therefore,
<i>words</i>
must not contain an unquoted newline
or any of the unquoted shell special characters:
<pre>
<code>
|   &amp;   ;   &lt;   &gt;
</code>
</pre>
except in the context of command substitution as specified in the <b>XCU</b> specification, <a href="../xcu/chap2.html#tag_001_006_003"><b>Command  Substitution</b>&nbsp;</a>.  It
also must not contain unquoted parentheses or braces, except in the context of
command or variable substitution.  If the argument
<i>words</i>
contains an unquoted comment character (number sign) that is the
beginning of a token,
<i>wordexp()</i>
may treat the comment character as a regular
character, or may interpret it as a comment indicator and ignore the
remainder of
<i>words</i>.
<p>
The structure type
<b>wordexp_t</b>
is defined in the header
<i><a href="wordexp.h.html">&lt;wordexp.h&gt;</a></i>
and includes at least the following members:
<p><table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Member Type</b>
<th align=center><b>Member Name</b>
<th align=center><b>Description</b>
<tr valign=top><td align=left>size_t
<td align=left>we_wordc
<td align=left>Count of words matched by <i>words</i>.
<tr valign=top><td align=left>char **
<td align=left>we_wordv
<td align=left>Pointer to list of expanded words.
<tr valign=top><td align=left>size_t
<td align=left>we_offs
<td align=left>Slots to reserve at the beginning of <i>pwordexp-&gt;</i><b>we_wordv</b>.
</table>
<p>
The
<i>wordexp()</i>
function stores the number of generated words into
<i>pwordexp->we_wordc</i>
and a pointer to a list of pointers to words in
<i>pwordexp->we_wordv</i>.
Each individual field created during
field splitting (see the <b>XCU</b> specification, <a href="../xcu/chap2.html#tag_001_006_005"><b>Field Splitting</b>&nbsp;</a>) or pathname expansion (see the <b>XCU</b> specification, <a href="../xcu/chap2.html#tag_001_006_006"><b>Pathname Expansion</b>&nbsp;</a>)
is a separate word in the
<i>pwordexp->we_wordv</i>
list.
The words are in order as described in the <b>XCU</b> specification, <a href="../xcu/chap2.html#tag_001_006"><b>Word Expansions</b>&nbsp;</a>.
The first pointer after the last word pointer will be a null pointer.
The expansion of special parameters described in the <b>XCU</b> specification, <a href="../xcu/chap2.html#tag_001_005_002"><b>Special Parameters</b>&nbsp;</a> is unspecified.
<p>
It is the caller's responsibility to allocate the storage
pointed to by
<i>pwordexp</i>.
The
<i>wordexp()</i>
function allocates other space as needed, including memory pointed to by
<i>pwordexp->we_wordv</i>.
The
<i>wordfree()</i>
function frees any memory associated with
<i>pwordexp</i>
from a previous call to
<i>wordexp()</i>.
<p>
The
<i>flags</i>
argument is used to control the behaviour of
<i>wordexp()</i>.
The value of
<i>flags</i>
is the bitwise inclusive OR of zero or more of the following constants,
which are defined in
<i><a href="wordexp.h.html">&lt;wordexp.h&gt;</a></i>:
<dl compact>

<dt>WRDE_APPEND<dd>
Append words generated to the ones from a previous call to
<i>wordexp()</i>.

<dt>WRDE_DOOFFS<dd>
Make use of
<i>pwordexp->we_offs</i>.
If this flag is set,
<i>pwordexp->we_offs</i>
is used to specify how many null
pointers to add to the beginning of
<i>pwordexp->we_wordv</i>.
In other words,
<i>pwordexp->we_wordv</i>
will point to
<i>pwordexp->we_offs</i>
null pointers, followed by
<i>pwordexp->we_wordc</i>
word pointers, followed by a null pointer.

<dt>WRDE_NOCMD<dd>
Fail if command substitution, as specified in the <b>XCU</b> specification, <a href="../xcu/chap2.html#tag_001_006_003"><b>Command  Substitution</b>&nbsp;</a>, is requested.

<dt>WRDE_REUSE<dd>
The
<i>pwordexp</i>
argument was passed to a previous successful call to
<i>wordexp()</i>,
and has not been passed to
<i>wordfree()</i>.
The result will be the same as if the application had
called
<i>wordfree()</i>
and then called
<i>wordexp()</i>
without WRDE_REUSE.

<dt>WRDE_SHOWERR<dd>
Do not redirect
<i>stderr</i>
to
<b>/dev/null</b>.

<dt>WRDE_UNDEF<dd>
Report error on an attempt to expand an undefined shell variable.

</dl>
<p>
The WRDE_APPEND
flag can be used to append a new set of words to those generated by a
previous call to
<i>wordexp()</i>.
The following rules apply when two or more calls to
<i>wordexp()</i>
are made with the same value of
<i>pwordexp</i>
and without intervening calls to
<i>wordfree()</i>:
<ol>
<p>
<li>
The first such call must not set WRDE_APPEND.
All subsequent calls must set it.
<p>
<li>
All of the calls must set WRDE_DOOFFS, or all must not set it.
<p>
<li>
After the second and each subsequent call,
<i>pwordexp->we_wordv</i>
will point to a list containing the following:
<ol type = a>
<p>
<li>
zero or more null pointers, as specified by WRDE_DOOFFS and
<i>pwordexp->we_offs</i>
<p>
<li>
pointers to the words that were in the
<i>pwordexp->we_wordv</i>
list before the call, in the same order as before
<p>
<li>
pointers to the new words generated by the latest call, in the
specified order
<p>
</ol>
<p>
<li>
The count returned in
<i>pwordexp->we_wordc</i>
will be the total number of words from all of the calls.
<br>
<p>
<li>
The application can change any of the fields after a call to
<i>wordexp()</i>,
but if it does it must reset them to the original value before a subsequent
call, using the same
<i>pwordexp</i>
value, to
<i>wordfree()</i>
or
<i>wordexp()</i>
with the WRDE_APPEND or WRDE_REUSE flag.
<p>
</ol>
<p>
If
<i>words</i>
contains an unquoted:
<pre>
<code>
&lt;newline&gt;   |   &amp;   ;   &lt;   &gt;   (   )   {   }
</code>
</pre>
<p>
in an inappropriate context,
<i>wordexp()</i>
will fail, and the number of expanded words will be 0.
<p>
Unless WRDE_SHOWERR is set in
<i>flags</i>,
<i>wordexp()</i>
will redirect
<i>stderr</i>
to
<b>/dev/null</b>
for any utilities executed as a result of command substitution while
expanding
<i>words</i>.
If WRDE_SHOWERR is set,
<i>wordexp()</i>
may write messages to
<i>stderr</i>
if syntax errors are detected
while expanding
<i>words</i>.
<p>
If WRDE_DOOFFS is set, then
must have the same value for each
<i>wordexp()</i>
call and
<i>wordfree()</i>
call using a given
<i>pwordexp</i>.
<p>
The following constants are defined as error return values:
<dl compact>

<dt>WRDE_BADCHAR<dd>
One of the unquoted characters:
<pre>
<code>
&lt;newline&gt;   |   &amp;   ;   &lt;   &gt;   (   )   {   }
</code>
</pre>

appears in
<i>words</i>
in an inappropriate context.

<dt>WRDE_BADVAL<dd>
Reference to undefined shell variable when WRDE_UNDEF is set in
<i>flags</i>.

<dt>WRDE_CMDSUB<dd>
Command substitution requested when WRDE_NOCMD
was set in flags.

<dt>WRDE_NOSPACE<dd>
Attempt to allocate memory failed.

<dt>WRDE_SYNTAX<dd>
Shell syntax error, such as unbalanced
parentheses or unterminated string.

</dl>
</blockquote><h4><a name = "tag_000_010_803">&nbsp;</a>RETURN VALUE</h4><blockquote>
On successful completion,
<i>wordexp()</i>
returns 0.
<p>
Otherwise, a non-zero value as described in
<i><a href="wordexp.h.html">&lt;wordexp.h&gt;</a></i>
is returned to indicate an error.  If
<i>wordexp()</i>
returns the value WRDE_NOSPACE, then
<i>pwordexp->we_wordc</i>
and
<i>pwordexp->we_wordv</i>
will be updated to reflect any words
that were successfully expanded.
In other cases, they will not be modified.
<p>
The
<i>wordfree()</i>
function returns no value.
</blockquote><h4><a name = "tag_000_010_804">&nbsp;</a>ERRORS</h4><blockquote>
No errors are defined.
</blockquote><h4><a name = "tag_000_010_805">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_010_806">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
This function is intended to be used by an application that wants to do
all of the shell's expansions on a word or words obtained from a user.
For example, if the application prompts for a filename (or list of
filenames) and then uses
<i>wordexp()</i>
to process the input,
the user could respond with anything that would be valid as
input to the shell.
<p>
The WRDE_NOCMD
flag is provided for applications that, for security or other reasons,
want to prevent a user from executing shell commands.
Disallowing unquoted shell special characters
also prevents unwanted side effects such as executing a command or
writing a file.
</blockquote><h4><a name = "tag_000_010_807">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_010_808">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="fnmatch.html">fnmatch()</a></i>,
<i><a href="glob.html">glob()</a></i>,
<i><a href="wordexp.h.html">&lt;wordexp.h&gt;</a></i>,
the <b>XCU</b> specification.
</blockquote><h4>DERIVATION</h4><blockquote>
Derived from the ISO POSIX-2 standard.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>

